User Manual
Table of Contents
System Requirements
Minimum System Requirements
- Windows with WebView2 Supported
uv installed
Installation & Setup
Packaged Version Installation (Recommended)
-
Download the Application
- Locate the
elevator.exe file provided by your instructor or system administrator
- Ensure the file is saved to an easily accessible location (e.g., Desktop or Program Files)
-
Verify File Integrity
- Check that the file size matches the expected distribution
- Scan with antivirus software if required by your organization
-
No Installation Required
- The application is portable and runs directly from the executable file
- No system modifications or registry changes are made

Source Code Version (For Developers)
-
Clone the Repository
-
Install Dependencies
-
Check Installation
- Ensure all dependencies are installed correctly
- Run the application using:
uv run main.py
Getting Started
Launching the Application
-
Standard Launch
- Double-click
elevator.exe to start the application
- Wait for the loading screen to complete (typically 3-5 seconds)
- The main simulation window will appear automatically
-
Verifying Successful Launch
- Look for the building visualization with two elevator shafts
- Confirm that floor call buttons are visible on the left side
- Check that elevator control panels are displayed on the right side

Understanding the Initial State
When the application starts:
- Both elevators begin at Floor 1 (ground floor)
- All doors are closed
- No active calls or destinations are set
- The system is ready to receive commands
🟢 Success Indicator: You should see two elevator cars positioned at Floor 1 with closed doors and no directional arrows lit.
Quick Start Tutorial
Follow these steps for your first interaction:
-
Call an Elevator
- Click the "▲" (up) button next to Floor 2
- Watch as one elevator begins moving upward
- Observe the directional arrow indicator
-
Select a Destination
- While the elevator is at Floor 2, click "3" in the elevator's control panel
- The elevator will move to Floor 3 automatically
-
Manual Door Control
- Click the "◀ ▶" button to open doors manually
- Click the "▶ ◀" button to close doors
🔵 Tip: Doors will automatically close after a few seconds if left open.
User Interface Overview
Main Window Layout
The application window consists of four main sections arranged for optimal usability:

A. Building Visualization (Top)
- Visual representation of the 5-floor building
- Elevator shafts with moving elevator cars
- Floor call buttons for summoning elevators
B. Elevator Control Panels (Middle)
- Individual control panels for each elevator
- Destination selection buttons
- Manual door control buttons
- Real-time floor and direction indicators
C. Status Information (Bottom)
- Current elevator positions
- Active calls and destinations
- System status messages
D. Debug Information (Bottom) [Optional]
- Technical details about elevator states
- Target floor queues
- Detailed status information
Building Visualization Details
Floor Layout:
- Floor 3: Top floor, down button only
- Floor 2: Middle floor, up and down buttons
- Floor 1: Ground floor, up and down buttons
- Floor -1: Basement, up button only
Elevator Cars:
- Numbered "1" and "2" for identification
- Visual door animation (opening/closing)
- Position updates in real-time
- Color coding for different states
Call Buttons:
- ▲ Up Button: Request elevator going upward
- ▼ Down Button: Request elevator going downward
- Active State: Buttons light up when pressed
- Reset: Buttons return to normal when elevator arrives
Control Panel Features
Each elevator has an identical control panel containing:
Floor Selection Buttons:
- Large, numbered buttons for each floor (3, 2, 1, -1)
- Buttons highlight when selected as destinations
- Multiple floors can be selected simultaneously
Door Control Buttons:
- "◀ ▶" Open Doors: Manually opens elevator doors
- "▶ ◀" Close Doors: Manually closes elevator doors
- Immediate response to button presses
Status Display:
- Floor Indicator: Shows current elevator floor
- Direction Arrows: Indicate movement direction (▲ up, ▼ down)
- Real-time Updates: Information updates continuously

🔵 Note: Debug information is hidden by default. Enable it using the --debug command line option.
The debug panel provides technical details:
- Current Floor: Precise floor position
- Status: Operating state (IDLE, MOVING_UP, MOVING_DOWN, etc.)
- Door: Door state (OPEN, CLOSED, OPENING, CLOSING)
- Target Floors: Queue of destination floors
Basic Operations
Calling an Elevator
Purpose: Summon an elevator to your current floor
Steps:
- Identify your current floor on the building visualization
- Determine your intended direction (up or down)
- Click the appropriate call button:
- ▲ for going up to higher floors
- ▼ for going down to lower floors
- Wait for the elevator to arrive (button will remain lit)
- The button will reset when an elevator reaches your floor
Example Scenario:
- You're on Floor 2 and want to go to Floor 3
- Click the "▲" button next to Floor 2
- Watch as the nearest available elevator moves to Floor 2
- The elevator doors will open automatically upon arrival
⚠️ Important: Always select the correct direction button. Elevators optimize their routes based on the direction of your call.
Selecting Your Destination
Purpose: Choose which floor you want to visit
Steps:
- Ensure you're "inside" an elevator (doors are open at your floor)
- Look at the control panel for the appropriate elevator
- Click the button corresponding to your destination floor
- The button will light up to confirm your selection
- The elevator will automatically close doors and move to your destination
Multiple Destinations:
- You can select multiple floors for one trip
- The elevator will visit floors in optimal order
- Each destination button will light up when selected
Floor Button Reference:
- "3": Top floor
- "2": Second floor
- "1": Ground floor (main entrance)
- "-1": Basement level

Manual Door Control
Purpose: Override automatic door operations
When to Use:
- Hold doors open for additional passengers
- Close doors immediately without waiting
- Emergency situations requiring door control
Open Doors Manually:
- Click the "◀ ▶" button in the elevator control panel
- Doors will open immediately
- Doors will remain open until manually closed or timeout occurs
Close Doors Manually:
- Click the "▶ ◀" button in the elevator control panel
- Doors will close immediately
- If elevator has destinations, movement will begin automatically
🔴 Safety Note: Manual door controls only work when the elevator is stopped at a floor. Moving elevators cannot have doors opened.
Command Line Options
The application supports several command line parameters for advanced users and system administrators.
Basic Command Line Usage
Opening Command Prompt:
- Press
Windows + R to open Run dialog
- Type
cmd and press Enter
- Navigate to the application directory using
cd command
- Run the application with desired options
Basic Syntax:
elevator.exe [OPTIONS]
Available Options
--debug
- Purpose: Enable debug information display
- Usage:
elevator.exe --debug
- Effect: Shows technical details in the bottom panel
- Recommended for: Troubleshooting, technical demonstrations
--headless
- Purpose: Run without graphical interface
- Usage:
elevator.exe --headless
- Effect: Starts backend services only, no GUI window
- Use case: Server deployments, automated testing
--ws-port [PORT]
- Purpose: Specify WebSocket communication port
- Usage:
elevator.exe --ws-port 18675
- Default: Automatically finds available port (18675-18775 range)
- Use case: Avoiding port conflicts, network restrictions
--http-port [PORT]
- Purpose: Specify HTTP server port
- Usage:
elevator.exe --http-port 19090
- Default: Automatically finds available port (19090-19190 range)
- Use case: Custom web server configuration
--zmq-port [PORT]
- Purpose: Set ZMQ communication port for external systems
- Usage:
elevator.exe --zmq-port 19982
- Default: 19982
- Use case: Integration with external test systems
--console
- Purpose: Force console output visibility
- Usage:
elevator.exe --console
- Effect: Shows terminal window with application messages
- Useful for: Monitoring system status, debugging
Common Command Line Examples
Debug Mode for Troubleshooting:
elevator.exe --debug --console
Headless Mode for Server:
elevator.exe --headless --http-port 8080
Custom Port Configuration:
elevator.exe --ws-port 18680 --http-port 19095
Full Debug with Custom Ports:
elevator.exe --debug --console --ws-port 18675 --http-port 19090
🔵 Tip: Command line options are particularly useful for system administrators or when running multiple instances of the application.